feat: route knative docs base URL from knative.dev/docs to knative.dev #6319
Conversation
- Updated base URL configuration from knative.dev/docs to knative.dev - Added comprehensive 301 redirects for smooth transition - Updated blog configuration to point to new base URL - Ensures backward compatibility with existing links and search results This change routes the base URL for Knative docs to knative.dev instead of knative.dev/docs, while maintaining backward compatibility through proper redirects that won't break search results or existing links.
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Welcome @rohan-019! It looks like this is your first PR to knative/docs 🎉 |
knative-prow
bot
added
the
size/S
|
/ok-to-test |
knative-prow
bot
added
the
ok-to-test
|
Hey, @rohan-019 ! Thanks for doing this. In the preview, I'm not seeing the described effect, though I can see that you made changes intended to produce this effect. Am I looking at something wrong? E.g. (and yes, serving HTML for a 301 is not great...) |
|
Hi @evankanderson, Thanks for checking! It looks like the root is still serving a redirect to /docs/, which means the Netlify build output path is probably still pointing at /docs. I’ll update the Netlify publish directory (or verify the MkDocs build path) so the docs are served directly at /. The 301 redirect from /docs/* → / will stay in place so existing links and crawlers are preserved. |
knative-prow
bot
added
size/M
knative-prow-robot
added
the
needs-rebase
knative-prow-robot
removed
the
needs-rebase
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: evankanderson, rohan-019 The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
knative-prow
bot
added
the
approved
No problem at all, and sorry for my late response too. Thanks for reviewing—I’ll check it now. |
|
I think (based on #6502), we may want the following URL structure:
I think that should minimize the amount of redirects / broken links that need to be adjusted, while moving all the non-technical documentation out of the versioned section. I don't know if we want to implement this as adding another layer |
rohan-019
force-pushed
the
blackboxai/route-base-url-to-knative-dev
branch
from
13ec24f to
1cc1ca0
Compare
Signed-off-by: rohan-019 <[email protected]>
knative-prow
bot
added
size/L
There was a problem hiding this comment.
I'm sorry that this is proving so gnarly!
I've tried poking a bit at your configuration, and I'm also having trouble figuring out the best path. So far, what I think might work:
- Keep the
build.shscript mostly the same. - Copy the
docs/index.htmlfromsiteup to the root level after the build, instead of creating thesite/index.htmldirectly. - You might consider doing the same treatment for
aboutandcommunity, and fixing the links inoverrides/partials/header.html, but that might be too much.
Sorry to have had a hidden minefield in here -- I'm guessing that's part of why it wasn't fixed previously!
Thanks a lot for the back-to-back responses. I’ll review and make the updates, then get back to you shortly. |
- Restore version JSON block for version picker functionality - Stop copying /about and /community into versioned builds - Restore API reference curl fetches for serving-api.md and eventing-api.md - Restore /development build step - Copy index.html and sitemap.xml to root after build - Update navigation to point to correct paths (root vs versioned) - Fix top-nav links to use proper URL structure
Home.-.Knative.-.Google.Chrome.2025-09-06.11-45-22.mp4What doesn't: Docs and Blog pages show "files not found" |
| # 2) Update VERSIONS below (on main) to include the new version, and remove the oldest | ||
| # Order matters :-), Most recent first. | ||
| VERSIONS=("1.18" "1.17") # Docs version, results in the url e.g. knative.dev/docs-1.9/.. | ||
| VERSIONS=("1.19" "1.18" "1.17") # Docs version, results in the url e.g. knative.dev/v1.9-docs/.. |
There was a problem hiding this comment.
We're not quite ready to release 1.19 -- the OpenTelemetry changes came in late and we've had to push some bug fixes.
| # Create docs directory structure | ||
| mkdir -p "$SITE/docs" | ||
|
|
||
| # Build latest docs to /docs |
There was a problem hiding this comment.
We were building the next-release docs to /development/... and the most-recent-release docs to /docs/.... I think you've changed this to build the next-release docs to /docs/..., and not publish docs for the current release anywhere.
| if [ "$BUILD_VERSIONS" == "no" ]; then | ||
| # HEAD to /docs if we're not doing versioning. | ||
| mkdocs build -f mkdocs.yml -d site/docs | ||
| # Build to root if we're not doing versioning | ||
| mkdocs build -f mkdocs.yml -d site |
There was a problem hiding this comment.
FWIW, this "tiny build for preview" seems to potentially be the part that's messing things up. I wonder if we want to remove it for now, and leave a TODO to optimize this later. (The preview version is also not importing the serving/eventing reference docs, and makes it hard to reason about these sorts of changes from the preview.)
| # Build development site | ||
| pushd "$TEMP/docs-main" | ||
| KNATIVE_VERSION="${VERSIONS[0]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[0]}" mkdocs build -f mkdocs.yml -d "$SITE/development" | ||
| popd |
There was a problem hiding this comment.
Why are we repeating 56-58 here?
| # Move non-versioned content to root level | ||
| mkdir -p "$SITE/about" | ||
| cp -r "$TEMP/docs-main/docs/about" "$SITE/" | ||
| mkdir -p "$SITE/community" | ||
| cp -r "$TEMP/docs-main/docs/community" "$SITE/" |
There was a problem hiding this comment.
I think this may break links for images, CSS, and JavaScript for these pages. I'll attempt another build with your changes this afternoon (I avoided this PR yesterday because I had a few other items and I really got pulled in on Friday).
There was a problem hiding this comment.
The index.html did seem to mostly work with just a copy, mostly because that page is largely hand-crafted HTML.
There are still a few items I'm trying to figure out in the navigation -- like why the "blog", "about", and "community" links don't show up in the navigation tabs, despite being in nav.html.
| # Create version JSON for version picker | ||
| versionjson="" | ||
| for i in "${!previous[@]}"; do | ||
| version=${previous[$i]} | ||
| versionjson+="{\"version\": \"v$version-docs\", \"title\": \"v$version\", \"aliases\": [\"\"]}," |
There was a problem hiding this comment.
This was previously in the loop on 60-74. I don't have a strong opinion, but it feels slightly odd to have the same loop twice with some other actions in between.
Thanks for the detailed feedback, @evankanderson I’ve noted the possible follow-ups from your review: Once you confirm whether the current changes work, I’ll be ready to address any of these (either here or in a follow-up PR as appropriate). |
|
Building the multi-version site and then moving |
|
I think I might have a solution, but it's a bit more invasive. Frankly, this never worked quite right to begin with (witness the homepage redirecting to |
What Happened 🔍 |
|
If you already have a more invasive fix in mind, I’m happy to wait for your direction and adjust this PR (or follow up in a new one) once the bigger change is in place. |
|
I have a partial fix that involves moving the documentation into a sub-directory, and doing one https://github.com/knative/docs/compare/main...evankanderson:docs:docs-rebuild?expand=1 (Ignore the blog changes, I think I screwed up something when committing things quickly.) I don't have things entirely fixed, but the changes to the nav partial seem to get the secondary bar nav working again: 
I need to get the sidebar nav to cut out one more level, which probably means overriding more partials, and adding some documentation about why we're doing what we're doing. |
|
(But I need to get out and run right now -- more updates later tonight, or feel free to ask questions / take my changes and run with them) |
|
Thanks for digging into this, @evankanderson Happy to either wait for your next update or pick up from your branch if that helps move things forward faster. |
|
Feel free to pull in changes from my branch, and I can add some PRs to your branch as well if you want. A few things from my branch:
|
knative-prow-robot
added
the
needs-rebase
|
PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
You probably saw, but #6371 merged, which I think includes this functionality. Thanks for starting on this, and highlighting a lot of the challenges. Your work probably saved me a couple days of trying things before I ended up with that PR (which is pretty big). There are still a number of additional cleanup items from that if you're interested:
Thanks again for getting this work started! I think the end result is an improvement, and I really viewed this as a team effort -- I wouldn't have done it without you. |
|
Hi @evankanderson, very sorry for the late reply — I got caught up with some other work last week. Really glad to see #6371 merged 🎉 It’s great that our back-and-forth and experiments led to that outcome. Thanks for building on the initial work I started and pushing it through — the end result looks like a big improvement. I appreciate the detailed notes on the follow-up cleanup tasks. I’d be happy to start looking into some of the smaller items, like directory moves or link consistency. I’ll also take a look at the CNCF Tech Doc Recommendations umbrella issue (#6301) to see where else I can contribute. Thanks again for treating this as a team effort — I learned a lot through this process and really enjoyed collaborating on it! |
…ive#6371) * Attempt to rebuild docs build process * Use a more modern python version * Fix strict verify, hide versions on unversioned pages
* Phase 1: Adding documentation metadata tags (#6274) * Add metadata tags for documentation * Add classification for about 2/3rds of docs (func + eventing) * Add classification for remainder of docs (serving+install) * Add mermaid support (#6327) * Publish threat model in documentation (#6263) * Publish threat model in documentation * Separate security contents a bit more, update link to threat model, update nav * Add a section on supply chain and SBOM/SLSA mitigation * Update threat model with feedback from David Hadas * Update introduction with content from davidhadas, add sections on controller and webhook functionality and update targets of threats * content tab fixes, added success output for kn func (#6367) * Add dry run section and take out old feature flag in serving (#6366) * add dry run section * drop mention of old feature flag * fix casing on nav * update docs to be more clear and include inline example --------- Co-authored-by: Dave Protasowski <[email protected]> * Attempt to rebuild docs build process, inspired by #6319 (#6371) * Attempt to rebuild docs build process * Use a more modern python version * Fix strict verify, hide versions on unversioned pages * Fix search with mkdocs typescript patches (vendored). (#6392) Hopefully, this can be fixed upstream via PR shortly. * Installation Doc Updates (#6395) * Installation Doc Updates Improve installation guidance * Formatting fix * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * link fix and table update More writing * Update README.md Misc edits * Update README.md Minor edits * Adding install-kn to PR Consolidating CLI installations into this this topic. * Update install-kn.md Changing red bug alert to important The old syntax was: ??? bug "Having issues upgrading `kn` to Homebrew?" * Update install-kn (snippet) Removed alert formatting * Added quickstart-install.md Various edits * Fixes and reviewed edits Made Evan suggestions, table column test, spelling fixes * Update quickstart-install.md link fix * Update README.md Replaced the table with a bulleted list approach. * Update README.md Put back the table * Added serving and eventing install topics Updated topics per effort - consolidating guidance * Link fixes * Made Evan's edits * Various updates All files added for this PR. * Link fix * Formatting fixes * Formatting and consistency fix * Update docs/install/operator/knative-with-operator-cli.md Co-authored-by: Evan Anderson <[email protected]> * Update docs/client/install-kn.md Co-authored-by: Evan Anderson <[email protected]> --------- Co-authored-by: Evan Anderson <[email protected]> * Fix edit page links, move technical docs under sub-heading (#6398) * Fix edit links by moving docs content under a dedicated subdirectory * Fix edit links by moving docs content under a dedicated subdirectory * Add High availability documentation section for eventing (#6401) I have copy-pasted from the Knative Serving documentation page the block as I found it missing when configuring it. * Update proc-running-function.md (#6400) Undo separeate kn func output for invoke * Add a note that Apache Kafka is required to use EKB (#6404) * Move install docs to administration (#6403) * Fix trailing newline complaints * Fix redirects from #6398 --------- Co-authored-by: Bruce Hamilton <[email protected]> Co-authored-by: Alexander-Kita <[email protected]> Co-authored-by: Dave Protasowski <[email protected]> Co-authored-by: Aurélien Joga <[email protected]> Co-authored-by: Christoph Stäbler <[email protected]>
Migrate documentation from /docs/* to root domain with 301 redirects
Overview
This PR restructures the Knative documentation URL hierarchy by moving content from
https://knative.dev/docs/*tohttps://knative.dev/*, creating a cleaner and more intuitive navigation experience.fixes: #6292
Changes Made
Configuration Updates
site_urlfromhttps://knative.dev/docstohttps://knative.devRedirect Strategy
Benefits
Testing Completed
/docs/*→/*redirects function correctlyImpact
/docs/*URLs remain functional via redirects